Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: Change docs theme to PyData Sphinx theme #2513

Merged
merged 5 commits into from
Jun 7, 2024
Merged

docs: Change docs theme to PyData Sphinx theme #2513

merged 5 commits into from
Jun 7, 2024
+8 −13

Conversation

melissawm
Copy link
Contributor

@melissawm melissawm commented Jun 5, 2024 •
edited by matthewfeickert
Loading

Description

This is a simple conversion of the documentation pages to the PyData Sphinx Theme using the default configurations for the theme.

From the documentation for the theme (https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/readthedocs.html#version-switcher) the version switcher from readthedocs should still work after this is done (but won't show up before the PR is merged). If you want to use the version switcher of the PyData Sphinx Theme instead, it would require having urls for all of the previous versions of the library and one json file mapping urls to versions. This would also enable using the Version warning banner from the PyData theme itself: https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/announcements.html#version-warning-banners

Closes #2512

Checklist Before Requesting Reviewer

  • [N/A] Tests are passing
  • "WIP" removed from the title of the pull request
  • Selected an Assignee for the PR to be responsible for the log summary

Before Merging

For the PR Assignees:

  • Summarize commit messages into a comprehensive review of the PR
* Switch docs theme to use the PyData Sphinx theme which is used across the
  broader Scientific Python community ubiquitously.
   - Replace sphinx-rtd-theme with pydata-sphinx-theme in 'docs' extra.
* Reorder the navigation bar to keep API reference sections visible by default.
* Remove 'View me on GitHub' ribbon.
   - The ribbon will cause issues with the theme and isn't needed anymore.
* Add Melissa Weber Mendonça to contributors list.

@matthewfeickert matthewfeickert changed the title Change docs theme to PyData Sphinx theme docs: Change docs theme to PyData Sphinx theme Jun 5, 2024
@matthewfeickert matthewfeickert added docs Documentation related need-to-backport tmp label until can be backported to patch release branch labels Jun 5, 2024
matthewfeickert
matthewfeickert approved these changes Jun 5, 2024
View reviewed changes
Copy link
Member

@matthewfeickert matthewfeickert left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @melissawm! This is great. :) As we talked about in person we might need to merge this to see if things work as expected on the RTD deployment RE: the version switcher, but I can also debug anything in follow up PRs.

@kratsg we should also consider moving things around in the ordering post this PR given that the API reference docs aren't immediately visible in the RTD preview (https://pyhf--2513.org.readthedocs.build/en/2513/).

@kratsg
Copy link
Contributor

kratsg commented Jun 6, 2024

@kratsg we should also consider moving things around in the ordering post this PR given that the API reference docs aren't immediately visible in the RTD preview (https://pyhf--2513.org.readthedocs.build/en/2513/).

wonder why the API docs disappear?

@matthewfeickert
Copy link
Member

wonder why the API docs disappear?

It isn't that they are gone, but just that the current docs deployment has them on a vertical bar on the left and the PyData Sphinx them has them on a horiztonal bar on the top.

image

vs.

image

@melissawm
Copy link
Contributor Author

I believe we can reorganize the order in which those sections appear - let me make sure the API docs are more prominent in the navbar.

@matthewfeickert
Copy link
Member

Thanks @melissawm. Though @kratsg and I could also do that in a follow up PR, as this PR gets things over the line in terms of being stylistically aligned with the rest of Scientific Python. 👍

kratsg
kratsg approved these changes Jun 6, 2024
View reviewed changes
Copy link
Contributor

@kratsg kratsg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

approved with the caveat of a follow-up to fix API docs

@codecov Codecov
Copy link

codecov bot commented Jun 7, 2024 •
edited
Loading

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.21%. Comparing base (7d316ef) to head (36c270c).
Report is 13 commits behind head on main.

Additional details and impacted files 
@@           Coverage Diff           @@
##             main    #2513   +/-   ##
=======================================
  Coverage   98.21%   98.21%           
=======================================
  Files          69       69           
  Lines        4543     4543           
  Branches      804      804           
=======================================
  Hits         4462     4462           
  Misses         48       48           
  Partials       33       33
Flag Coverage Δ
contrib 97.79% <ø> (ø)
doctest 98.08% <ø> (ø)
unittests-3.10 96.23% <ø> (ø)
unittests-3.11 96.23% <ø> (ø)
unittests-3.12 96.23% <ø> (ø)
unittests-3.8 96.25% <ø> (ø)
unittests-3.9 96.27% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@matthewfeickert matthewfeickert added the build Changes that affect the build system or external dependencies label Jun 7, 2024
@matthewfeickert matthewfeickert merged commit e8789a2 into scikit-hep:main Jun 7, 2024
24 checks passed
@matthewfeickert
Copy link
Member

Thanks for your PR @melissawm — your contributions are very appreciated!

@matthewfeickert
Copy link
Member

From the documentation for the theme (https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/readthedocs.html#version-switcher) the version switcher from readthedocs should still work after this is done (but won't show up before the PR is merged). If you want to use the version switcher of the PyData Sphinx Theme instead, it would require having urls for all of the previous versions of the library and one json file mapping urls to versions. This would also enable using the Version warning banner from the PyData theme itself: https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/announcements.html#version-warning-banners

From https://pyhf.readthedocs.io/en/latest/ seems like we'll need the to use the PyData Sphinx Theme version switcher.

@matthewfeickert matthewfeickert mentioned this pull request Jun 7, 2024
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@matthewfeickert matthewfeickert matthewfeickert approved these changes

@kratsg kratsg kratsg approved these changes

Assignees

@melissawm melissawm

Labels
build Changes that affect the build system or external dependencies docs Documentation related need-to-backport tmp label until can be backported to patch release branch
Projects
pyhf v0.8.0
Status: Done
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Move documentation pages to PyData Sphinx Theme
3 participants
@melissawm @kratsg @matthewfeickert